table of contents
TIMER_SETTIME(2) | Linux Programmer's Manual | TIMER_SETTIME(2) |
NAME¶
timer_settime, timer_gettime - arm/disarm and fetch state of POSIX per-process timer
SYNOPSIS¶
#include <time.h> int timer_settime(timer_t timerid, int flags, const struct itimerspec *new_value, struct itimerspec * old_value); int timer_gettime(timer_t timerid, struct itimerspec *curr_value);
Link with -lrt.
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
timer_settime(), timer_gettime(): _POSIX_C_SOURCE >= 199309
DESCRIPTION¶
timer_settime() arms or disarms the timer identified by timerid. The new_value argument is an itimerspec structure that specifies the new initial value and the new interval for the timer. The itimerspec structure is defined as follows:
struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds */ }; struct itimerspec {
struct timespec it_interval; /* Timer interval */
struct timespec it_value; /* Initial expiration */ };
Each of the substructures of the itimerspec structure is a timespec structure that allows a time value to be specified in seconds and nanoseconds. These time values are measured according to the clock that was specified when the timer was created by timer_create()
If new_value->it_value specifies a non-zero value (i.e., either subfield is non-zero), then timer_settime() arms (starts) the timer, setting it to initially expire at the given time. (If the timer was already armed, then the previous settings are overwritten.) If new_value->it_value specifies a zero value (i.e., both subfields are zero), then the timer is disarmed.
The new_value->it_interval field specifies the period of the timer, in seconds and nanoseconds. If this field is non-zero, then each time that an armed timer expires, the timer is reloaded from the value specified in new_value->it_interval. If new_value->it_interval specifies a zero value then the timer expires just once, at the time specified by it_value.
By default, the initial expiration time specified in new_value->it_value is interpreted relative to the current time on the timer's clock at the time of the call. This can be modified by specifying TIMER_ABSTIME in flags, in which case new_value->it_value is interpreted as an absolute value as measured on the timer's clock; that is, the timer will expire when the clock value reaches the value specified by new_value->it_value. If the specified absolute time has already passed, then the timer expires immediately, and the overrun count (see timer_getoverrun(2)) will be set correctly.
If the value of the CLOCK_REALTIME clock is adjusted while an absolute timer based on that clock is armed, then the expiration of the timer will be appropriately adjusted. Adjustments to the CLOCK_REALTIME clock have no effect on relative timers based on that clock.
If old_value is not NULL, then it returns the previous interval of the timer (in old_value->it_interval) and the amount of time until the timer would previously have next expired (in old_value->it_value).
timer_gettime() returns the time until next expiration, and the the interval, for the timer specified by timerid, in the buffer pointed to by curr_value. The time remaining until the next timer expiration is returned in curr_value.it_value; this is always a relative value, regardless of whether the TIMER_ABSTIME flag was used when arming the timer. If the value returned in curr_value.it_value is zero, then the timer is currently disarmed. The timer interval is returned in curr_value.it_interval. If the value returned in curr_value.it_interval is zero, then this is a "one-shot" timer.
RETURN VALUE¶
On success, timer_settime() and timer_gettime() return 0. On error, -1 is returned, and errno is set to indicate the error.
ERRORS¶
These functions may fail with the following errors:
timer_settime() may fail with the following errors:
- EINVAL
- new_value.it_value is negative; or new_value.it_value.tv_nsec is negative or greater than 999,999,999.
VERSIONS¶
These system calls are available since Linux 2.6.
CONFORMING TO¶
POSIX.1-2001
EXAMPLE¶
See timer_create(2).
SEE ALSO¶
timer_create(2), timer_settime(2), timer_getoverrun(2), time(7)
COLOPHON¶
This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.
2009-02-20 | Linux |